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FUSE 

File systems in User SpacE 
f use.so u reef o rge. net/ 
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People tend to think it's a C library 

Nope 
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It's a Linux kernel API 

With a request-response protocol spoken over a fd 
Userspace is the server 
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The C library is the reference implementation 

... named exactly the same as the kernel API :( 

All the things you'd expect from a project hosted at SourceForge in 201 3. 
Well call it "C FUSE" from here on. 
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Others provide similar libraries 

C libraries more or less API compatible with the C FUSE API. 

May even be forks of it. 

Lots of platform-specific extensions. 

OSX: 

osxfuse.github.com/ 

(originally code.google.eom/p/macfuse/ 

or github.com/macfuse/macfuse) 

- MacFUSE is dead upstream, forks ahoy 

Windows: dokan-dev.net/en/ 
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ha n wen/go-fuse 

Han-Wen Nienhuys wrote a go-fuse library. 
The structure of its API leaves a lot to be desired. 
Use it if you want. Good luck. 

Personally, I think writing a library from scratch would be less painful. 
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rsc to the rescue 

Russ Cox's fuse library can be found at code, google, com/p/rsc/f use 
code.google.eom/p/rsc/source/browse/#hg%2Ffuse 

Bazil is a fork of it. With a name that doesn't match /fuse/. 

(Strictly, Bazil is an umbrella project, bazil.org/fuse is the FUSE library. 

So that was a lie. But call it "Bazil FUSE" if you need to.) 

Hopefully our contributions help improve the state of the ecosystem. 

Russ seems to develop mostly on OS X, Tv is a Linux person. 
Both should work. OS X contributions are most welcome. 
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Bazil is an independent implementation 

Pure-Go implementation of userspace server for the Linux and OS X kernel protocols. 

Linux kernel support is upstream, 

OS X needs the f usef s kernel module from OSXFUSE. 

On Linux: uses setuid f user mount userspace mount helper from the C FUSE package. 

Many things you read about "FUSE" are about C FUSE, and don't apply to Bazil. 
For example: automatic inode numbering, multithreading. 
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Understanding FUSE 

Kernel interface 

Docu mentatio n/fi lesyste ms/f use.txt 
i ncl ude/ua pi/I in ux/fuse. h 

numbered message types, wire structures, various constants 
C FUSE API docs, "experimental": 

fuse.sourceforge.net/doxygen/structfuse_lowlevel_ops.html 
fuse.sou rceforge.net/doxygen/structf use_operatio ns. htm I 
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Kernel API 

mount (2) is given a file descriptor. 

Bazil uses /bin/f usermount as subprocess (to handle /etc/mtab and 

such), passes a socketpairfd to it 

source 

From there on, it's just reads and writes on the fd. 
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Kernel protocol 



RequestID: 

to match response to request 
lifetime ends with response 

NodelD: 

directory entry kernels knows about 
kernel tells when to forget 

HandlelD: 

open file 

kernel tells when to destroy 
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Low-level C FUSE 

C FUSE'S low-level API exposes kernel requests and responses quite directly. 
Dispatches in inode numbers, explicit response. Typical to see helper wrappers. 

static void hello_ll_getattr(fuse_req_t req, fuse_ino_t ino, 

struct fuse_f ile_inf o *fi) 

{ 

struct stat stbuf ; 
(void) fi; 

memset(&stbuf , 0, sizeof (stbuf )); 
if (hellG^statUno, &stbuf) == -1) 
fuse_reply_err(req J ENOENT) ; 

else 

fuse_reply_attr(req, &stbuf, 1.0); 

} 



source 
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Low-level C FUSE, 2 




static int hell o_st a t ( tu s e_ino_t mOj struct stat *stbuf) 




{ 




stbuf ->st_ino = ino; 




switch (ino) { 




case 1 : 




stbuf->st_mode = S_IFDIR 


0755; 




stbuf ->st__nlink = 2; 




break; 




case 2: 




stbuf->st_mode = S_IFREG 


0444; 




stbuf ->st_nlink = 1 ; 




stbuf ->st_size = strlen(hello_str) ; 




break; 




default : 




return -1 ; 




} 




return 0; 




} 


source 
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High-level C FUSE 

Dispatches on path names instead of inode numbers. 
Response is implicit. Less need for helper wrappers. 

static int hello_getattr ( const char *path, struct stat *stbuf) 
{ 

int res = 0; 

memset(stbuf , 0, sizeof (struct stat)); 
if (strcmptpath, "/") == 0) { 

stbuf->st_mode = S_IFDIR | 0755; 

stbuf->st_nlink = 2; 
} else if (strcmp(path, hello_path) == 0) { 

stbuf->st_mode = S_IFREG | 0444; 

stbuf ->st_nlink = 1 ; 

stbuf->st_size = strlen(hello_str) ; 
} else 

res = -ENOENT; 

return res; 

} 

source 
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Bazil API 

Bazil doesn't do either inode number or path dispatching. 

Instead, it mirrors kernel data structures, with uint64 handles to objects. 

It's also significantly closer to the wire protocol. 

Requests are served by methods on the node itself, not a global dispatch function. 
Feel free to construct an in-memory tree, for simple filesystems. 
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Interfaces 

A Node must implement Attr(). Everything else is optional. 

For example, if a node does not implement Remove( ), unlink(2) on it will always fail. 

Documentation of possible interfaces is severely lacking right now. 
Need to explore how to maintain it in sync with the code. 
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Directory lookup in Bazil 

Kernel struct dentry maps to fuse . Node, identified on wire with fuse . NodelD. 

LookupO returns a Node, a reference is kept in a map [NodelD] Node until a Forget () 
call 
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Open files in Bazil 

Open file: kernel struct file maps to fuse . Handle, identified on wire with 
fuse.HandlelD. 

Open() returns a Handle (maybe self), which is kept in a map [HandlelD] Handle until a 
Destroy () call. 

close(2) has two parts: 

per f d method Releasee ) that returns error (for delayed writes and such), 
and a final Destroy ( ) that always succeeds. 
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Let's Go! 



type File struct{} 

func (File) AttrQ fuse.Attr { 
return f use. Attr {Mode: 0444} 

} 
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File content 

func (File) ReadAll( intr fuse.Intr) ([]byte, fuse. Error) { 
return []byte( "hello, world\n"), nil 

} 

ReadAll( ) caches the whole content in memory and serves smaller reads from that. 

It's convenient for pseudofiles. 

There's also Read( ) for more realistic use. 
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Looking up the file by name 

type Dir struct {} 

func (Dir) Attr{) fuse.Attr { 

return fuse. Attr{Inode: 1, Mode: os.ModeDir | 0555} 

} 

func (Dir) Lookup (name string, intr fuse.Intr) (fuse. Node, fuse. Error) { 
if name = "hello" { 
return File{} f nil 

} 

return nil, fuse.ENOENT 

} 
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Starting point 

type FS struct{} 

func (FS) Root() (fuse. Node, fuse. Error) { 
return Dir{}, nil 

} 
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Listing files 

var dirOirs = []fuse.Dirent{ 

{Inode: 2, Name: "hello", Type: fuse.DT_File}, 

} 

func (Dir) ReadDir(intr fuse.Intr) ([]fuse.Dirent, fuse. Error) { 
return dirDirs, nil 

} 
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Boilerplate 

// Copyright 2012 The Go Authors. All rights reserved. 
// Use of this source code is governed by a BSD-style 
// license that can be found in the LICENSE file. 

// Hellofs implements a simple "hello world" file system, 
package main 

import ( 
"flag" 
"fmt" 
"log" 

"OS" 

"bazil.org/fuse" 

) 

var Usage = func() { 

fmt .Fprintf (os.Stderr # "Usage of %s:\n", os.Args[0] ) 
fmt.Fprintf(os.Stderr, " %s MOUNTPOINT\n" , os.Args[0]) 
flag . PrintDef aults( ) 

} 
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...and Go! 

func main() { 

flag. Usage = Usage 
flag.Parse() 

if flag.NArgQ 1= 1 { 
Usagef) 
os. Exit (2) 

} 

mount point := flag.Arg(O) 

c, err := fuse . Mount ( mountpoint ) 
if err != nil { 
log. Fatal(err) 

} 

c.Serve(FS{}) 
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Bazil internals 

API decisions in bazil.org/fuse 
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Special Error type 

Bazil methods return fuse. Error and not Go's usual error. 

It has hidden knowledge of what POSIX errno to return to kernel. 

Use one of fuse. EIO, fuse. EPERM, fuse. ENOENT, fuse. ENOSYS, fuse. ESTALE, etc. 

Worst case, use fuse . Errno(syscall . ENOTDIR) etc. 
Ideally, Bazil will provide ready errors for all those. 
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Inode numbers 

If you don't fill in inode numbers in your Attr() etc calls, Bazil will hash the full path to 
create a pseudorandom inode number. 

These may collide, causing confusion in low-level tools like find. 

This also currently forces Bazil to remember full pathname to every Node. 
Details are likely to change, if a cheaper replacement scheme can be figured out. 

If you care, manage inode numbers explicitly. 
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Concurrency 





for 


{ 






reCj j err .— C ■ KeauKeCIUeST ^ J 






if err 1= nil { 






if err == io.EOF { 






break 






> 






return err 

1 C LUI II C 1 1 






} 






go c.serve(fs, req) 




> 





Each request is served in a separate goroutine. 



Sort of like net/http. 

If you mutate shared data, use mutexes. 
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Bazillion Bytes 

bazil.org/ 

FUSE can be FUN 

Go do it 
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Thank you 

Tommi Virtanen 

tv@eagain.net 
@tv 
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